Skip to content

feat: admin_origin, for a local stand-in of Shopify (local-storefront) - #34

Merged
0xtlt merged 1 commit into
masterfrom
feat/admin-origin
Nov 8, 2026
Merged

0xtlt merged 1 commit into
masterfrom
feat/admin-origin

Conversation

@0xtlt

@0xtlt 0xtlt commented Nov 8, 2026

Copy link
Copy Markdown
Owner

Adds an admin origin: the requests shopify_api builds from a shop's domain can go to another origin than https://{shop}. The use case is a local fake of Shopify such as local-storefront (http://localhost:9292), so that openshop-rust can run against it. A mock server or a proxy works too.

Without the option, nothing changes. The existing tests still assert the exact https://{shop}/… URLs, and a new test checks that no X-Forwarded-Host is sent.

Public API

// crates/shopify_api/src/origin.rs, re-exported at the root
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct AdminOrigin(/* private */);
impl AdminOrigin {
    pub fn new(origin: &str) -> Result<AdminOrigin, Error>;
    pub fn as_str(&self) -> &str; // "http://localhost:9292", no trailing slash
}
// + Display, AsRef<str>, FromStr<Err = Error>, TryFrom<&str, Error = Error>

impl ShopifyBuilder {
    pub fn admin_origin(self, origin: impl AsRef<str>) -> ShopifyBuilder; // checked by build()
}
impl Shopify {
    pub fn admin_origin(&self) -> Option<&AdminOrigin>;
}
// feature `oauth`
impl ShopifyApp {
    pub fn with_admin_origin(self, origin: impl AsRef<str>) -> Result<ShopifyApp>;
    pub fn admin_origin(&self) -> Option<&AdminOrigin>;
}

ShopifyApp::builder and ShopifyApp::client give the app's origin to the clients they build, the same way they pass on the transport and the token store. A later .admin_origin(…) on the builder replaces it.

What follows the origin

The option replaces only the scheme, host and port. Paths stay Shopify's.

Address Before With admin_origin("http://localhost:9292")
GraphQL (graphql_url) https://{shop}/admin/api/{v}/graphql.json http://localhost:9292/admin/api/{v}/graphql.json
Token endpoint: code exchange, token exchange, client credentials, refresh https://{shop}/admin/oauth/access_token http://localhost:9292/admin/oauth/access_token
Install link (authorization_url, browser-facing) https://{shop}/admin/oauth/authorize?… http://localhost:9292/admin/oauth/authorize?…&shop={shop}

grep -rn 'https://{' crates/ finds these three, plus ShopDomain::origin(). ShopDomain::origin() stays the shop's identity, and the session-token dest/iss check uses it.

The shop is still the shop. Session tokens are still verified against https://{shop} and https://{shop}/admin, which is what lsf mints. Errors, logs and TokenStore::save still name {shop}.myshopify.com.

When the host no longer names the shop, the shop is named another way:

  • Requests sent to the origin carry X-Forwarded-Host: {shop}. lsf reads this header to pick the shop (see explicit_shop in lsf's admin/auth/oauth.rs, and origin_of: "clients send the shop's domain in it"). It matters for the client credentials grant: without it, lsf uses its default shop.
  • Browser-facing URL: I chose to make the install link follow the option. lsf serves GET /admin/oauth/authorize. Without the change, the browser would go to real Shopify for a shop that only exists locally, and the callback would bring a code lsf can't exchange. The link also gets a last shop={shop} parameter, which lsf reads ("with &shop= for a shop other than the default one"). Without it, lsf would approve for its default shop.

Validation (at build time, Error::Config)

  • The origin must be an absolute http:// or https:// URL: a host and an optional port 1-65535. No path (a trailing / is fine), no query, no fragment, no userinfo.
  • http:// is only accepted for localhost, 127.0.0.1 and [::1], so a real access token never leaves the machine in clear text. I took the list literally. 127.0.0.2, app.localhost, 0.0.0.0 and [::ffff:127.0.0.1] are refused over http:// and accepted over https://.
  • Hosts must be DNS names (labels [a-z0-9-]), dotted IPv4 or bracketed IPv6. A host whose last label is a number must be a well-formed IPv4 address, so https://999.1.1.1 and https://127.000.000.001 are refused.
  • The origin is normalized: lowercase scheme and host, no trailing /, canonical IP form.
  • Following the crate's rules for what errors may show, an error never echoes the input, which may hold a password. A case was added to no_variant_shows_a_secret. ShopifyBuilder's Debug doesn't show the raw input either.

Bulk results

Bulk results URLs (lsf answers http://localhost:9292/__lsf/admin/bulk/<shop>/<n>.jsonl) and staged-upload targets are absolute and used as they come. There was never any check on them to loosen, so nothing changed for real hosts. The default transport already fetched http://127.0.0.1:<port>/… (tests/bulk_stream.rs). A new test downloads from {origin}/__lsf/admin/bulk/… and checks that neither a token nor X-Forwarded-Host is sent.

Tests

  • src/origin.rs unit tests cover accepted and normalized origins, refused ones (35 cases), http only for loopback, errors that don't show the input, and URL building.
  • src/client.rs and src/oauth.rs unit tests cover graphql_url with and without the option, an invalid origin refused by build(), the install link with shop, propagation to ShopifyApp::builder, and session tokens still verified for the shop.
  • tests/admin_origin.rs runs against a local HTTP server on localhost:<port> through the real ReqwestTransport:
    • a token exchange followed by a GraphQL query (path, X-Shopify-Access-Token, X-Forwarded-Host, subject_token);
    • the client credentials grant followed by a query;
    • a bulk download from the origin;
    • with MockTransport: no option means exact https://{shop} URLs and no extra header.

Checks run locally

I ran these with the rustup 1.99.1 toolchain, the version mise.toml pins:

  • cargo fmt --all -- --check: ok
  • cargo clippy --workspace --all-targets --all-features --locked -- -D warnings: ok
  • cargo test --workspace --all-features --locked: 384 passed, 0 failed
  • cargo test -p shopify_api --locked: 100 passed
  • check:features (4 × cargo check --no-default-features …, cargo test --no-default-features --doc, 29 doctests): ok
  • RUSTDOCFLAGS=-D warnings cargo doc --workspace --all-features --no-deps --locked: ok
  • cargo +1.88 check --workspace --all-features --locked (MSRV): ok
  • cargo package --workspace --locked: ok
  • cargo deny check: advisories, bans, licenses and sources ok

The version is not bumped and nothing is published. openshop-rust will use this branch through [patch.crates-io] until a release that contains it is published.

🤖 Generated with Claude Code

`ShopifyBuilder::admin_origin` and `ShopifyApp::with_admin_origin` send the
requests built from the shop's domain (GraphQL, the client credentials grant,
refresh tokens, the code and token exchanges) and the install link of
`authorization_url` to another origin than `https://{shop}`: a local fake of
Shopify such as local-storefront (`http://localhost:9292`), a mock server, a
proxy. Only the scheme, the host and the port change. The shop stays the
identity of the session tokens, the tokens and the errors; the requests sent
to the origin name it in `X-Forwarded-Host`, and the install link in a last
`shop` parameter, so that one origin can serve several shops.

`AdminOrigin` checks it when the client is built: an absolute `https://` URL,
or `http://` to `localhost`, `127.0.0.1` or `[::1]` only, with no path, query
string, fragment or user. Anything else is an `Error::Config` that does not
show what was given. Without the option, nothing changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xtlt
0xtlt merged commit e45b5ac into master Nov 8, 2026
6 checks passed
@0xtlt
0xtlt deleted the feat/admin-origin branch November 8, 2026 14:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant